---
title: Date Field
description: A date field allows users to enter and edit date and time values using a keyboard.
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/DateField.html
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/dates/date-field.mdx?plain=1
---

<ComponentPreview
  name="date-field/demos/default"
  preview={`<DateField aria-label="Meeting date" />`}
/>

## Installation

```package-install
npx shadcn@latest add @dotui/date-field
```

## Usage

Use a `DateField` to allow users to enter and edit time values using a keyboard.

```tsx
import { DateField } from "@/components/core/date-field";

<DateField label="Event date" description="Please select your event date." />;
```

```tsx
import { DateFieldInput, DateFieldRoot } from "@/components/core/date-field";
import { Description, FieldError, Label } from "@/components/core/field";

<DateFieldRoot>
  <Label>Event date</Label>
  <DateFieldInput />
  <Description>Please select your event date.</Description>
  <FieldError />
</DateFieldRoot>;
```

## Uncontrolled

An initial, uncontrolled value can be provided to the `DateField` using the `defaultValue` prop.

<ComponentPreview
  name="date-field/demos/uncontrolled"
  preview={`<DateField defaultValue={parseDate("2020-02-03")} />`}
/>

## Controlled

Use the `value` and `onChange` props to control the value of the input.

<ComponentPreview
  name="date-field/demos/controlled"
  preview={`const [value, setValue] = React.useState(parseDate("2020-02-03"));
  return <DateField value={value} onChange={setValue} />`}
/>

## Options

### Label

A visual label can be provided for the `DateField` using the `label` prop or a hidden label using `aria-label` prop.<br/>

<ComponentPreview
  name="date-field/demos/label"
  preview={`<DateField label="Meeting date" />
<DateField aria-label="Meeting date" />`}
/>

### Size

Use the `size` prop to control the size of the `DateField`.<br/>
The default variant is `"md"`.

<ComponentPreview
  name="date-field/demos/sizes"
  preview={`<DateField size="sm" />
<DateField size="md" />
<DateField size="lg" />`}
/>

### Prefix and suffix

To add additional context for the `DateField`, such as an icon, use the `prefix` and `suffix` props.

<ComponentPreview
  name="date-field/demos/prefix-and-suffix"
  preview={`<DateField prefix={<CalendarIcon />} />
<DateField suffix={<CalendarIcon />} />`}
/>

### Description

A description can be supplied to `DateField` via the `description` prop. The description is always visible unless the `isInvalid` prop is `true` and an error message is provided.

<ComponentPreview
  name="date-field/demos/description"
  preview={`<DateField label="Appointment" description="Please select a date." />`}
/>

### Error message

An `errorMessage` can be supplied to `DateField`, which will be displayed when the `isInvalid` prop is set to `true`.

<ComponentPreview
  name="date-field/demos/error-message"
  preview={`<DateField
    label="Meeting"
    isInvalid
    errorMessage="Meetings can't be scheduled in the past."
  />`}
/>

### Disabled

Use the `isDisabled` prop to disable the DateField.

<ComponentPreview
  name="date-field/demos/disabled"
  preview={`<DateField label="Event date" isDisabled />`}
/>

### ReadOnly

The `isReadOnly` boolean prop makes the DateField's text content immutable. Unlike isDisabled, the DateField remains focusable and the contents can still be copied.

<ComponentPreview
  name="date-field/demos/read-only"
  preview={`<DateField label="Event date" value={new CalendarDate(1980, 1, 1)} isReadOnly />`}
/>

### Required

Use the `isRequired` prop to mark the DateField as required.
Use the `necessityIndicator` prop to control the visual style of the required state.

<ComponentPreview
  name="date-field/demos/required"
  preview={`<DateField label="Event date" isRequired />`}
/>

## Value options

### Time zones

`DateField` is time zone aware when a ZonedDateTime object is provided as the value.

<ComponentPreview
  name="date-field/demos/time-zones"
  preview={`<DateField
    aria-label="Meeting time"
    defaultValue={parseZonedDateTime("2022-11-07T00:45[America/Los_Angeles]")}
  />`}
/>

### Granularity

The `granularity` prop allows you to control the smallest unit that is displayed by DateField.

<ComponentPreview
  name="date-field/demos/granularity"
  preview={`<DateField
    label="Hour"
    granularity="hour"
    defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
  />
  <DateField
    label="Minute"
    granularity="minute"
    defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
  />
  <DateField
    label="Second"
    granularity="second"
    defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
  />`}
/>

## Format Options

### Placeholder value

Use the `placeholderValue` prop to control the default values of each segment. The default value is midnight.

<ComponentPreview
  name="date-field/demos/placeholder"
  preview={`<DateField label="Meeting date" placeholderValue={new CalendarDate(1980, 1, 1)} />`}
/>

### Hide time zone

Use the `hideTimeZone` prop to hide the time zone abbreviation.

<ComponentPreview
  name="date-field/demos/hide-time-zone"
  preview={`<DateField
    label="Appointment time"
    granularity="minute"
    defaultValue={parseZonedDateTime("2022-11-07T10:45[America/Los_Angeles]")}
    hideTimeZone
  />`}
/>

### Hour cycle

Use the `hourCycle` prop to control the hour cycle of the DateField.

<ComponentPreview
  name="date-field/demos/hour-cycle"
  preview={`<DateField aria-label="Meeting time" granularity="minute" hourCycle={24} />`}
/>

## Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview
  name="date-field/demos/composition"
  preview={`<DateFieldRoot>
    <Label>Meeting time</Label>
    <DateFieldInput />
    <Description>Please select a time between 9 AM and 5 PM.</Description>
  </DateFieldRoot>`}
/>

## API Reference

| Prop                      | Type                                                                                                   | Default  | Description                                                                                                                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minValue`                | `DateValue`                                                                                            | -        | The minimum allowed date that a user may select.                                                                                                                                                                                      |
| `maxValue`                | `DateValue`                                                                                            | -        | The maximum allowed date that a user may select.                                                                                                                                                                                      |
| `isDateUnavailable`       | `(date: DateValue) => boolean`                                                                         | -        | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.                                                                                                                              |
| `placeholderValue`        | `DateValue`                                                                                            | -        | A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle.                                                                          |
| `hourCycle`               | `12 \| 24`                                                                                             | -        | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.                                                                                                                             |
| `granularity`             | `'hour' \| 'minute' \| 'second'`                                                                       | -        | Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.                                                                                                       |
| `hideTimeZone`            | `boolean`                                                                                              | `false`  | Whether to hide the time zone abbreviation.                                                                                                                                                                                           |
| `shouldForceLeadingZeros` | `boolean`                                                                                              | -        | Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale.                                                                                                                          |
| `isDisabled`              | `boolean`                                                                                              | -        | Whether the input is disabled.                                                                                                                                                                                                        |
| `isReadOnly`              | `boolean`                                                                                              | -        | Whether the input can be selected but not changed by the user.                                                                                                                                                                        |
| `isRequired`              | `boolean`                                                                                              | -        | Whether user input is required on the input before form submission.                                                                                                                                                                   |
| `isInvalid`               | `boolean`                                                                                              | -        | Whether the input value is invalid.                                                                                                                                                                                                   |
| `validate`                | `(value: MappedDateValue<DateValue>) => ValidationError  \| true  \| null  \| undefined`               | -        | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead. |
| `autoFocus`               | `boolean`                                                                                              | -        | Whether the element should receive focus on render.                                                                                                                                                                                   |
| `isOpen`                  | `boolean`                                                                                              | -        | Whether the input value is invalid.                                                                                                                                                                                                   |
| `defaultOpen`             | `boolean`                                                                                              | -        | Whether the input value is invalid.                                                                                                                                                                                                   |
| `value`                   | `DateValue \| null`                                                                                    | -        | The current value (controlled).                                                                                                                                                                                                       |
| `defaultValue`            | `DateValue \| null`                                                                                    | -        | The default value (uncontrolled).                                                                                                                                                                                                     |
| `name`                    | `string`                                                                                               | -        | The name of the input element, used when submitting an HTML form.                                                                                                                                                                     |
| `validationBehavior`      | `'native' \| 'aria'`                                                                                   | `'aria'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.                                                                        |
| `children`                | `ReactNode \| (values: DateFieldRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | -        | The children of the component. A function may be provided to alter the children based on component state.                                                                                                                             |
| `className`               | `string`                                                                                               | -        | The CSS className for the element.                                                                                                                                                                                                    |
| `style`                   | `CSSProperties \| (values: DateFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -        | The inline style for the element. A function may be provided to compute the style based on component state.                                                                                                                           |

| Event           | Type                                          | Description                                                     |
| --------------- | --------------------------------------------- | --------------------------------------------------------------- |
| `onFocus`       | `(e: FocusEvent<Target>) => void`             | Handler that is called when the element receives focus.         |
| `onBlur`        | `(e: FocusEvent<Target>) => void`             | Handler that is called when the element loses focus.            |
| `onFocusChange` | `(isFocused: boolean) => void`                | Handler that is called when the element's focus status changes. |
| `onKeyDown`     | `(e: KeyboardEvent) => void`                  | Handler that is called when a key is pressed.                   |
| `onKeyUp`       | `(e: KeyboardEvent) => void`                  | Handler that is called when a key is released.                  |
| `onOpenChange`  | `(isOpen: boolean) => void`                   | Handler that is called when the overlay's open state changes.   |
| `onChange`      | `(value: MappedDateValue<DateValue>) => void` | Handler that is called when the value changes.                  |

| Data attribute    | Description                         |
| ----------------- | ----------------------------------- |
| `[data-invalid]`  | Whether the date field is invalid.  |
| `[data-disabled]` | Whether the date field is disabled. |

## Accessibility

### Keyboard interactions

| Key                      | Description                                                                                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tab`                    | Places focus on the first segment. If a segment is already in focus, moves focus to the next segment. If last segment in in focus, moves focus to the next element in the page tab sequence. |
| `ArrowRight` `ArrowLeft` | Moves focus between segments.                                                                                                                                                                |
| `ArrowUp` `ArrowDown`    | Increments/decrements the value of the segment.                                                                                                                                              |
